home *** CD-ROM | disk | FTP | other *** search
/ Total Network Tools 2002 / NextStepPublishing-TotalNetworkTools2002-Win95.iso / Archive / Web Server / PHP.EXE / pear / PHPDoc / analyser / PhpdocModuleAnalyser.php < prev   
Encoding:
PHP Script  |  2001-02-18  |  13.5 KB  |  370 lines
  1. <?php
  2. /**
  3. * Analyses a modulegroup.
  4. *
  5. * @version $Id: PhpdocModuleAnalyser.php,v 1.5 2001/02/18 15:19:15 uw Exp $
  6. */
  7. class PhpdocModuleAnalyser extends PhpdocAnalyser {
  8.  
  9.     /**
  10.     * Module data
  11.     *
  12.     * @var  array
  13.     */
  14.     var $modulegroup        = array();
  15.  
  16.     /**
  17.     * List of all modules in the modulegroup
  18.     *
  19.     * @var  array
  20.     */ 
  21.     var $modulelist = array();
  22.     
  23.     /**
  24.     * Puuuh - findUndocumented() needs this.
  25.     *
  26.     * @var    array
  27.     * @see    findUndocumented()
  28.     */                                                        
  29.     var $undocumentedFields = array(
  30.                                     "functions" => "function",
  31.                                     "uses"      => "included file",
  32.                                     "consts"    => "constant"
  33.                                );
  34.  
  35.     /**
  36.     * Sets the data of the modulegroup to analyse.
  37.     * 
  38.     * @param    array    Raw modulegroup data from the parser.
  39.     * @access    public
  40.     */
  41.     function setModulegroup($modulegroup) {
  42.     
  43.         $this->modulegroup = $modulegroup;    
  44.         
  45.     } // end func setModulegroup
  46.     
  47.     function analyse() {
  48.  
  49.         $this->flag_get = false;
  50.         
  51.         $this->buildModulelist();
  52.         
  53.         $this->updateAccessReturn();
  54.         $this->updateBrothersSisters();
  55.         $this->checkSee();
  56.                 
  57.         $this->checkFunctionArgs();
  58.         $this->findUndocumented();
  59.         
  60.     } // end func analyse
  61.     
  62.     /**
  63.     * Returns a module from the modulegroup or false if there are no more modules.
  64.     *
  65.     * @return   mixed   False if there no more modules in the modulegroup otherwise
  66.     *                   an array with the data of a module.
  67.     * @access   public
  68.     */
  69.     function getModule() {
  70.     
  71.         if (!$this->flag_get) {
  72.             reset($this->modulelist);
  73.             $this->flag_get = true;
  74.         }
  75.             
  76.         if (list($modulename, $group) = each($this->modulelist)) {
  77.             
  78.             $module = $this->modulegroup[$group][$modulename];
  79.             unset($this->modulegroup[$group][$modulename]);            
  80.             return $module;
  81.             
  82.         } else {
  83.         
  84.             return false;
  85.             
  86.         }
  87.         
  88.     } // end func getModule
  89.     
  90.     function findUndocumented() {
  91.  
  92.         reset($this->modulegroup);
  93.         while (list($group, $modules) = each($this->modulegroup)) {
  94.             
  95.             reset($modules);
  96.             while (list($name, $module) = each($modules)) {
  97.                 
  98.                 reset($this->undocumentedFields);
  99.                 while (list($index, $eltype) = each($this->undocumentedFields)) {
  100.                     if (!isset($module[$index]))
  101.                         continue;
  102.                         
  103.                     $file = $module["filename"];
  104.                     
  105.                     reset($module[$index]);
  106.                     while (list($elname, $data) = each($module[$index]))
  107.                         if (isset($data["undoc"]) && $data["undoc"])
  108.                             $this->warn->addDocWarning($file, $eltype, $elname, "Undocumented element.", "missing");
  109.                 }
  110.                 
  111.             }
  112.             
  113.         }        
  114.  
  115.     } // end func findUndocumented
  116.     
  117.     function checkFunctionArgs() {
  118.     
  119.         reset($this->modulegroup);
  120.         while (list($group, $modules) = each($this->modulegroup)) {
  121.  
  122.             reset($modules);
  123.             while (list($name, $module) = each($modules)) {
  124.                 if (!isset($module["functions"]))
  125.                     continue;
  126.  
  127.                 $file = $module["filename"];
  128.                                 
  129.                 reset($module["functions"]);
  130.                 while (list($fname, $function) = each($module["functions"])) {
  131.                     $this->modulegroup[$group][$name]["functions"][$fname]["params"] = $this->checkArgDocs($function["args"], $function["params"], $fname, $file, false);
  132.                     unset($this->modulegroup[$group][$name]["functions"][$fname]["args"]);
  133.                 }
  134.                 
  135.             }
  136.             
  137.         }
  138.  
  139.     } // end func checkFunctionArgs
  140.     
  141.     /**
  142.     * Builds an internal list of all modules in the modulegroup.
  143.     *
  144.     * @see  $modulelist, $modulegroup
  145.     */
  146.     function buildModulelist() {
  147.     
  148.         $this->modulelist = array();
  149.         
  150.         reset($this->modulegroup);
  151.         while (list($group, $modules) = each($this->modulegroup)) {
  152.         
  153.             reset($modules);
  154.             while (list($modulename, $data) = each($modules))
  155.                 $this->modulelist[$modulename] = $group;
  156.                 
  157.         }
  158.         
  159.     }
  160.  
  161.         
  162.     function updateBrothersSisters() {
  163.     
  164.         reset($this->modulelist);
  165.         while (list($modulename, $group) = each($this->modulelist)) {
  166.             $this->updateBrotherSisterElements($group, $modulename, "functions");
  167.             $this->updateBrotherSisterElements($group, $modulename, "variables");
  168.         }    
  169.         
  170.     } // end func updateBrothersSisters
  171.     
  172.     /**
  173.     * @param    string  Modulegroupname
  174.     * @param    string  Modulename
  175.     * @param    string  Elementtype: functions, variables.
  176.     * @return   boolean    
  177.     */
  178.     function updateBrotherSisterElements($group, $modulename, $type) {
  179.         
  180.         if (!isset($this->modulegroup[$group][$modulename][$type])) 
  181.             return false;
  182.             
  183.         reset($this->modulegroup[$group][$modulename][$type]);
  184.         while (list($elementname, $data) = each($this->modulegroup[$group][$modulename][$type])) {
  185.             
  186.             if (isset($data["brother"])) {
  187.  
  188.                 $name = ("functions" == $type) ? substr($data["brother"], 0, -2) : substr($data["brother"], 1);
  189.                 $name = strtolower($name);
  190.  
  191.                 if (!isset($this->modulegroup[$group][$modulename][$type][$name])) {
  192.                 
  193.                     $this->warn->addDocWarning($this->modulegroup[$group][$modulename]["filename"], $type, $elementname, "Brother '$name' is unknown. Tags gets ignored.", "mismatch");
  194.                     unset($this->modulegroup[$group][$modulename][$type][$elementname]["brother"]);
  195.                     
  196.                 } else {
  197.                 
  198.                     $this->modulegroup[$group][$modulename][$type][$elementname]["brother"] = $name;
  199.                     $this->modulegroup[$group][$modulename][$type][$elementname] = $this->copyBrotherSisterFields($this->modulegroup[$group][$modulename][$type][$elementname], $this->modulegroup[$group][$modulename][$type][$name]);
  200.                     
  201.                 }
  202.  
  203.             }
  204.             
  205.         }
  206.         
  207.     } // end func updateBrotherSistersElements
  208.     
  209.     function updateAccessReturn() {
  210.         
  211.         reset($this->modulelist);
  212.         while (list($modulename, $group) = each($this->modulelist)) {
  213.         
  214.             if (!isset($this->modulegroup[$group][$modulename]["access"]))
  215.                 $this->modulegroup[$group][$modulename]["access"] = "private";
  216.                 
  217.             $this->updateAccessReturnElements($group, $modulename, "functions");
  218.             $this->updateAccessReturnElements($group, $modulename, "variables");
  219.             $this->updateAccessElements($group, $modulename, "consts");        
  220.             
  221.         }
  222.                 
  223.     } // end func updateAccessReturn
  224.     
  225.     /**
  226.     * @param    string  Modulegroup
  227.     * @param    string  Modulename
  228.     * @param    string  Elementtype: functions, variables, consts.
  229.     * @return   boolean
  230.     */
  231.     function updateAccessReturnElements($group, $modulename, $type) {
  232.         
  233.         if (!isset($this->modulegroup[$group][$modulename][$type]))
  234.             return false;
  235.  
  236.         reset($this->modulegroup[$group][$modulename][$type]);
  237.         while (list($elementname, $data) = each($this->modulegroup[$group][$modulename][$type])) {
  238.         
  239.             if (!isset($data["access"])) 
  240.                 $this->modulegroup[$group][$modulename][$type][$elementname]["access"] = "private";
  241.                 
  242.             if (!isset($data["return"]))
  243.                 $this->modulegroup[$group][$modulename][$type][$elementname]["return"] = "void";
  244.                 
  245.         }
  246.                 
  247.     } // end func updateAccessReturnElements
  248.     
  249.     /**
  250.     * @param    string  Modulegroup
  251.     * @param    string  Modulename
  252.     * @param    string  Elementtype: functions, variables, consts.
  253.     * @return   boolean
  254.     */
  255.     function updateAccessElements($group, $modulename, $type) {
  256.         
  257.         if (!isset($this->modulegroup[$group][$modulename][$type]))
  258.             return false;
  259.             
  260.         reset($this->modulegroup[$group][$modulename][$type]);
  261.         while (list($elementname, $data) = each($this->modulegroup[$group][$modulename][$type])) {
  262.             
  263.             if (!isset($data["access"])) 
  264.                 $this->modulegroup[$group][$modulename][$type][$elementname]["access"] = "private";
  265.         
  266.         }
  267.         
  268.     } // end func updateAccessElements
  269.     
  270.     function checkSee() {
  271.  
  272.         reset($this->modulegroup);
  273.         while (list($group, $modules) = each($this->modulegroup)) {
  274.  
  275.             while (list($modulename, $module) = each($modules)) {
  276.         
  277.                 $this->buildElementlist($group, $modulename);
  278.                 
  279.                 if (isset($module["functions"])) 
  280.                     $this->checkSeeElements($module["functions"], $group, $modulename, "functions");
  281.                     
  282.                 if (isset($module["variables"]))
  283.                     $this->checkSeeElements($module["variables"], $group, $modulename, "variables");
  284.                 
  285.                 if (isset($module["consts"])) 
  286.                     $this->checkSeeElements($module["consts"], $group, $modulename, "consts");
  287.                     
  288.                 if (isset($module["uses"]))
  289.                     $this->checkSeeElements($module["uses"], $group, $modulename, "uses");
  290.                 
  291.             }    
  292.             
  293.         }
  294.         
  295.     } // end func checkSee
  296.  
  297.     /**
  298.     * Checks see references in the given element array (functions, variables...)
  299.     *
  300.     * References to variables and functions within the same module get checked.
  301.     * It the references element does not exist, the reference gets deleted and 
  302.     * a doc warning gets generated.
  303.     * 
  304.     * @param    array   List of functions, variables,...
  305.     * @param    string  Name of the modulegroup that contains the given elements.
  306.     * @param    string  Name of the module that contains the given elements.
  307.     * @param    string  Elementtype: functions, variables, consts, uses.
  308.     */    
  309.     function checkSeeElements($elements, $modulegroup, $modulename, $eltype) {
  310.  
  311.         reset($elements);
  312.         while (list($elname, $element) = each($elements)) {
  313.         
  314.             if (isset($element["see"])) {
  315.                 
  316.                 if (isset($element["see"]["var"])) {
  317.                     
  318.                     reset($element["see"]["var"]);
  319.                     while (list($k, $variable) = each($element["see"]["var"])) 
  320.                         if (!isset($this->elementlist["variables"][strtolower($variable["name"])])) {
  321.                             $this->warn->addDocWarning($this->modulegroup[$modulegroup][$modulename]["filename"], "variables", $elname, "@see referrs to the variable '" . $variable["name"] . "' which is not defined in the class. Entry gets ignored.", "mismatch");
  322.                             unset($this->modulegroup[$modulegroup][$modulename][$eltype][$elname]["see"]["var"][$k]);
  323.                         }
  324.  
  325.                 }
  326.                 
  327.                 if (isset($element["see"]["function"])) {
  328.                     
  329.                     reset($element["see"]["function"]);
  330.                     while (list($k, $function) = each($element["see"]["function"]))
  331.                         if (!isset($this->elementlist["functions"][strtolower(substr($function["name"], 0, -2))])) {
  332.                             $this->warn->addDocWarning($this->modulegroup[$modulename]["filename"], "functions", $elname, "@see referrs to the function '" . $function["name"] . "' which is not defined in the class. Entry gets ignored.", "mismatch");
  333.                             unset($this->modulegroup[$modulegroup][$modulename][$eltype][$elname]["see"]["function"][$k]);
  334.                         }
  335.  
  336.                 }
  337.                 
  338.             }
  339.             
  340.         }    
  341.         
  342.     } // end func checkSeeElement
  343.     
  344.     /**
  345.     * Builds an array with all elements of a class and saves it to $this->elementlist.
  346.     * 
  347.     * @param    string  Name of the modulegroup that contains the module.
  348.     * @param    string  Name of the module to scan.
  349.     */
  350.     function buildElementlist($modulegroup, $modulename) {
  351.         
  352.         $elements = array();
  353.         $fields = array("functions", "variables", "consts", "uses");
  354.         
  355.         reset($fields);
  356.         while (list($k, $field) = each($fields)) 
  357.             if (isset($this->modulegroup[$modulegroup][$modulename][$field])) {
  358.                 
  359.                 reset($this->modulegroup[$modulegroup][$modulename][$field]);
  360.                 while (list($element, ) = each($this->modulegroup[$modulegroup][$modulename][$field])) 
  361.                     $elements[$field][$element] = true;
  362.                     
  363.             }
  364.         
  365.         $this->elementlist = $elements;
  366.         
  367.     } // end func buildElementlist
  368.     
  369. } // end class PhpdocModuleAnalyser
  370. ?>